游戏接入样例

在阅读本文档之前，推荐您先阅读快速使用手册，如果您是技术人员，推荐您优先阅读的数据接入指南中的相关章节。另外，您可以下载游戏接入方案样例进行参考，帮助您快速构建接入方案。

前言

第一次使用TGA的用户，往往会在准备阶段产生很多疑惑——如何转化分析需求、应该收集哪些的属性、如何进行埋点等等，而基于Event & User模型的数据分析需要有良好的基础，如果在准备阶段无法解决这些疑惑，将会直接影响分析时的效果。为了避免准备阶段的困惑造成的不良影响，特此撰写本接入样例以解决您的困惑。

本接入样例主要面向运营人员、数据分析师以及负责埋点的技术人员，解决该收集哪些事件、设置什么属性、如何埋点等。本样例将会详细介绍游戏分析普遍需要收集的数据以及收集的方式，并尽可能地考虑到不同的游戏类型及游戏玩法，力求满足各类型游戏的分析需求，同时我们还会提供一些分析的思路，帮助您快速体验TGA平台的强大功能。

一、如何确定接入方案

进行游戏接入的第一步，就是将分析需求转化为接入方案。初次使用TGA平台的用户，可能对 Event & User 模型还不甚了解，不知道如何将已有的埋点转化为 Event 与 User 的形式；或者不清楚应该追踪哪些玩法和系统，如何进行埋点。在本节中我们将会给出确定与转化分析需求的简要过程，在第三节中将会详细介绍每个玩法或系统的具体如何转化：

1.1 创建接入文档

我们推荐在项目开始之前，创建一个用以记录分析需求的接入文档，将需要分析的玩法、系统以及对应的分析点都记录在文档中，您可以参考卷首的方案样例构建自己的接入文档。

1.2 明确账号体系

(1) 在大多数情况下，您的用户都会有一个账号ID用以表示其身份，在这种情况下，您只需要将您的游戏的账号ID作为TGA中用户的账号ID即可。

(2) 如果您的游戏存在访客游玩，或者您的游戏是无需登录的单机游戏，那么就需要在上传数据之前先调用identify来配置您的访客ID。

(3) 另外您需要考虑这样的情况，您的用户可以创建多个角色，而您也需要在分析时以角色为单位，我们建议您使用角色ID作为用户的主要标识，而将用户的账号ID作为事件的公共属性（即每个事件中都带有），同时在用户属性中记录该角色的账号ID，具体的实现方式将会在后续章节中详细介绍。

最后将您的账号体系写入接入文档中，比如是否需要访客ID，以及主要标识是使用角色ID还是账号ID。

1.3 确定分析需求

对于游戏中大大小小的系统与玩法，推荐将重要的玩法和系统设定为一个事件（Event），也就是埋点中的一个点，事件的名称为玩法的名称，比如，再根据您的分析点进行属性的设置；次要的玩法，可以合并为一个事件，通过一个标识属性（说明是哪种玩法的属性）来区分玩法。如果特别关注玩法中的某些行为，比如组队副本的组队行为，可以单独将这一行为作为一个事件进行追踪。

除此之外，还需要决定用户属性，用户属性是具有区分用户意义的属性，比如VIP等级、注册时间、累计付费金额等，或者是用户的基本信息，比如，

一般情况下，一个游戏需要的事件一般在50个左右，对于玩法复杂的游戏而言，可能需要100个事件左右，因此建议将这些内容记录在接入文档中。

1.4 转化分析需求

在确定完分析需求，也就是需要追踪的事件之后，您需要做的是决定每个事件的触发条件和属性，在第三节中将会详细说明如何进行转化，在此不多作赘述。

最后将转化完成的分析需求整理到接入文档中。

二、核心事件属性以及用户属性的设置

在确定完需要追踪的事件之后，接下来需要考虑如何设置核心事件属性与用户属性，这两类属性会作用于所有的Event，因此需要在设置每个Event的事件属性之前进行设置。

（1）核心事件属性：

事件属性指的是产生行为时带有的属性，不同的事件会带有不同的属性，但有部分重要的属性是每个事件都需要带有的，这些属性主要是玩家的各种ID或者区服、渠道等核心属性，常见的核心事件属性如下：

1.角色ID：如果在您的游戏中一个用户可以创建多个角色，那么我们极力推荐将角色ID设置为事件属性。在分析具体玩法时使用角色作为单位会更准确，而在分析新增、日活或者付费时使用用户ID。

2.区服：如果您对分区服有分析需求，建议将区服作为事件属性。

3.渠道：如果您对分渠道有分析需求，建议将渠道作为事件属性。

4.等级：将等级作为事件属性，可以对用户产生某行为时的等级进行分析。

除了上述通用的属性之外，还可以根据需要加入您游戏中重要的属性，比如VIP等级、用户名等。

在数据传输时，核心事件属性和其他事件属性并没有区别，两者的差别只是在于设置埋点阶段，一般情况下，建议在设置每个事件的单独属性前先确定这些核心属性，如果之后需要新增事件，也应该带有这些核心属性。

（2）用户属性：

用户属性是每个用户带有的属性，通过用户ID与事件进行关联，在考虑用户属性时需要注意两点:

1.如果在您的游戏中一个用户可创建多个角色时，则等级、区服等基于角色而非用户的用户属性可能会表意不准确，因此需要根据需求选择设置的方案。

2.用户属性可以根据意义分为三类，固定属性、最新状态以及累计值，不同类型的属性设置时调用的接口不同；固定属性是一经设置不再改变的属性，一般使用user_setOnce进行设置；最新状态是每次更新都会覆盖先前值的属性，使用user_set进行设置；累计值是数值型的属性，每次更新会在之前的值上进行加减计算，使用user_add进行设置。因此在设置用户属性之前，需要考虑清楚该属性的类型以确定设置时应调用的接口。

最后在设置完用户属性后，请将用户属性以及设置时调用的接口（或“#type”）写入接入文档中。另外，在设置属性名时，我们建议您使用有意义的词开头来提示属性的类型，比如以“first”开头表示首次触发的行为属性，以"latest"开头表示最新状态，以"sum"或"count"表示累计值。

我们推荐您设置以下用户属性：

1.区服：如果您的游戏可以创建多个角色，那么一个用户可能会有不同区服的角色，您需要选择是使用固定属性还是最新状态，在创建角色或登录时设置。

2.渠道：一般情况下用户的渠道不会有改变，可以直接作为固定属性，您也可以将其作为最新状态，可在创建角色或登录时设置。

3.等级：如果您的游戏可以创建多个角色，那么一个用户可能会有不同等级的角色，此时我们推荐将其作为最新状态在升级时进行设置。如果您的游戏一个账号只对应一个角色，那么除了作为最新状态以外，还可以使用累计值的设置方法，每次升级进行累加。

4.注册时间：固定属性，在注册时设置。

5.首次登录时间、最后登录时间：这两个属性分别是固定属性和最新属性，在登录时设置。

6.首次付费时间、最后付费时间：同样是固定属性与最新属性，在付费时设置。

7.累计付费金额：累计值，在付费时设置。

8.VIP等级：与等级类似，可作为最新状态或者累计值。

除此之外，您还可以根据需求加入合适的属性，比如固定属性可以设置用户的地理信息，最新状态可以设置最大通过关卡，累计值的付费次数、游玩天数或者副本挑战次数等。

三、设置每个事件的属性

设置完核心事件属性与用户属性之后，就可以开始设置每个事件的属性，事件属性与事件触发的条件是两个最为重要的因素，直接影响到数据分析的深度。本节将会详细介绍游戏中常见的玩法和系统应该如何设置触发条件和属性。

我们将会对每种玩法或系统提供几种设置的方案，并且以下列形式进行介绍：

• 方案名

【触发条件】：该方案的事件触发条件

【属性】：该方案主要推荐设置的属性，以及可以在此时设置的用户属性。您可以按需进行增删

【介绍】：详细描述该方案的优劣以及提供的可分析角度

1.注册、登录与创建角色的设置

首先介绍的是注册与登录事件，一般情况下，注册和登录事件是显性的，是在整个游戏之初触发的事件，同时也是设置许多用户属性的时机，因此需要注意公共事件属性需要在此之前进行设置。

• 注册事件

【触发条件】：注册完成后

【属性】：渠道，可以调用user_setOnce设置用户的注册时间

【介绍】：注册事件一般只用来统计新增人数，对于注册前行为有分析需求的可以使用下面的方案

• 注册前行为

【触发条件】：注册之前，包括注册完成后

【属性】：渠道，注册前行为的步骤（需要包括注册行为）

【介绍】：我们推荐您使用一个Event来记录所有注册前行为，通过“步骤”这一属性来区分注册前的每一步。您可以使用漏斗分析来分析注册前行为。

• 登录事件

【触发条件】：登录完成后

【属性】：核心属性（角色ID，等级，区服，渠道等下同），角色性别，职业等，可以调用user_setOnce设置用户的首次登录时间，调用user_set设置用户的最后登录时间

【介绍】：登录事件可以设置与角色相关的属性，比如职业等，您也可以加入如“是否首次登录”这样的属性进行进一步的分析。

• 创建角色

【触发条件】：创建角色完成后

【属性】：核心属性，角色性别，职业等

【介绍】：如果您对角色的创建有分析需求，可以设置角色创建事件，用以分析用户对角色的选择偏好。

2.如何处理付费行为

付费行为是游戏中最重要的事件，对于处理付费行为，我们主要提供以下几种方案：

• 付费完成

【触发条件】：完成付费后

【属性】：核心属性，订单号，付费金额，支付方式，购买项目等，调用user_add设置累计付费金额，调用user_setOnce设置用户的首次付费时间和首次付费金额，调用user_set设置用户的最后付费时间

【介绍】：您可以直接在每次用户完成付费后触发事件，这种方式比较简单，但对于未付费成功的订单没有监控，对此有需求可以使用后续方案。

• 付费订单的发起（与完成）

【触发条件】：订单发起时（与完成付费后）

【属性】：核心属性，订单号，订单状态（如果您希望使用同一事件记录订单发起与订单完成，可以使用该属性区分两者），付费金额，支付方式，购买项目等，在订单完成后调用user_add设置累计付费金额，调用user_setOnce设置用户的首次付费时间和首次付费金额，调用user_set设置用户的最后付费时间

【介绍】：与付费完成后触发事件类似，您只需在发起订单时同样上传一个事件，您可以通过漏斗模型或者通过订单号与付费完成事件进行关联，即可监控订单异常的情况。

• 订单异常

【触发条件】：订单未正常完成时

【属性】：核心属性，订单号，异常原因，付费金额，支付方式，购买项目等。

【介绍】：如果您的游戏中可以捕捉到订单异常及其原因，我们推荐您设置一个事件追踪订单异常的情况，便于您进行监控与查询。

3.玩家升级应该收集什么数据

玩家升级是游戏中十分常见的事件，其触发条件也十分清晰，即玩家升级时触发，主要考虑的是需要收集哪些属性

• 玩家升级

【触发条件】：玩家升级后

【属性】：核心属性，升级后等级，升级所需时间，升级原因等。调用user_set直接设置用户的升级后等级。

【介绍】：需要注意两点：（1）一个账号能够对应多个角色的情况，可能会导致用户属性的混乱，因此请使用user_set来设置等级；（2）可能出现一次升级提升数级的情况，此时需要考虑是否要上传多个事件来表示连续升级。

4.货币与道具的监控

货币与道具共同构建了游戏的经济系统，对于货币与道具的监控，我们推荐以流水明细表的形式来记录货币与道具的消耗获取情况。另外我们推荐您将重要的货币，如钻石（与实际货币挂钩的货币）和金币（主要的货币）单独设置一个事件来记录各自的流水明细，而将次要的货币、代币记录在一个事件中，通过“货币种类”属性来区分。

我们极力建议，诸如道具ID、货币类型等会出现在多个事件中的属性，请在相关的所有事件中使用相同的属性名。

• 钻石（金币）消耗获取流水明细

【触发条件】：获得或消耗钻石（金币）时

【属性】：核心属性，货币类型，消耗或获得数量，是否消耗，消耗或获得原因，现有资源数等等。

【介绍】：货币的流水明细，关键的属性是“消耗获得数”以及“消耗或获得原因”，前者有两种方式可以表示，第一种是通过“是否消耗”这一属性表明是消耗还是获得，“消耗获得数”只传入正值，即消耗与获得的绝对值，第二种方法只使用“消耗获得数”这一属性，通过传入值的正负来表明是消耗还是获得，我们建议您使用第一种方案。至于“消耗或获得原因”的取值，您可以直接传入中文值来明确表示消耗或获得的原因，或者传入ID，再通过设置字典的方式。

以上提供的是货币流水的最简范式，您还可以将获得与消耗作为两个事件来记录，也可以将商店购买的行为也作为一个事件。

• 商店购买

【触发条件】：商店购买完成后

【属性】：核心属性，商店类型，货币类型，消耗数量，购买道具ID，购买数量等。

【介绍】：商店购买需要注意的几个点，首先游戏中可能存在多个商店，您可以通过设置多个事件，也可以只设置一个事件加“商店类型”属性做区分。其次商店购买行为可能涉及多种货币类型，建议设置属性以标明使用货币的类型，不推荐因为某商店只消耗一种货币而省略“货币类型”的做法。最后如果您同时追踪了货币流水明细、道具流水明细以及商店购买行为这三个事件，我们建议您在用户产生购买行为时上传这三个事件，并且按照消耗货币（货币流水明细）、购买完成（商店购买）以及购得道具（道具流水明细）的顺序记录。

• 道具消耗获取流水明细

【触发条件】：获得或消耗道具时

【属性】：核心属性，道具ID，消耗或获得数量，是否消耗，消耗或获得原因，现有资源数等等。

【介绍】：道具流水明细与货币流水明细类似，建议此事件中的道具ID与商店购买中的购买道具ID使用相同的属性名。

对于经济系统的监控，我们建议尽可能地加强事件之间的联系。不同事件中表示同一意义的属性请使用同样的属性名，比如道具ID等。如果同时产生货币与道具的数量变更，建议此时两事件的“消耗与获得原因”的值也设置成相同值，以表示同一原因。

5.关卡与任务的设置

关卡与任务在很多方面相当类似，因此放在一块介绍，根据分析深度以及玩法复杂度的不同，提供以下几种方案：

• 关卡（任务）最简方案

【触发条件】：关卡结算时，任务接受与完成时

【属性】：核心属性，关卡（任务）ID，关卡（任务）类型，是否完成。

【介绍】：最简方案通过“是否完成”这一属性来判断关卡的通关与失败、任务的接受与完成，只设置一个事件，而不是在关卡与任务的各个阶段设置多个事件。这种方案可以满足大多数的分析需求，比如关卡驻留、关卡胜率以及任务完成情况，并且设置简单。缺点在于无法对关卡或任务的某一环节进行深入分析，比如关卡胜利后的资源获得、关卡失败的原因以及阶段性任务的追踪等等。

如果您希望更深入地分析，可以在关卡或任务的每一阶段都设置一个事件，此处给出每一阶段可供参考的设置方案：

• 挑战关卡

【触发条件】：进入关卡时

【属性】：核心属性，关卡ID，关卡类型，当前战斗力，出场英雄，是否首次挑战等

• 关卡通过

【触发条件】：关卡通过时

【属性】：核心属性，关卡ID，关卡类型，当前战斗力，获得资源ID，获得资源数量，出场英雄，是否首次通过等首次通过时调用user_set设置用户的最远通过关卡

• 关卡失败

【触发条件】：关卡通过时

【属性】：核心属性，关卡ID，关卡类型，当前战斗力，失败原因等等

• 任务接受

【触发条件】：接受任务时

【属性】：核心属性，任务ID，任务类型，

• 任务完成

【触发条件】：任务完成时

【属性】：核心属性，任务ID，任务类型，完成任务所用时间，任务奖励资源ID，奖励资源数量，获得活跃度等

【介绍】：您可以在关卡与任务的各阶段都设置一个事件，并且根据需要加入属性，您还可以将重要的副本或任务独立作为一个事件，比如BOSS副本或者日常任务。

6.其他玩法

除了上述提到的玩法和系统外，还有很多玩法没有提及，比如养成玩法、英雄系统、游戏外分享等等，您可以按照上述事件的设置方案来设置这些事件，主要需要注意以下几点：

（1）一个事件最重要的是触发条件以及属性，同一玩法在不同条件下触发会有不同的意义，需要根据您的分析需求进行设置。

（2）不同事件中相同意义的属性尽量使用同一属性名，TGA会将其视作同一属性。

（3）对于一些重要的状态值，比如参与特定玩法几次或者首次参与某活动的时间，可以将其设置为用户属性，在适当的时间调用合适的方法。